home *** CD-ROM | disk | FTP | other *** search
/ Clipper Collection / Clipper Collection.iso / clipper7 / acc86.arc / ACCI86.DOC next >
Text File  |  1987-10-23  |  49KB  |  1,950 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.                                   ACCI86.LIB
  16.                                  USERS MANUAL
  17.  
  18.  
  19.                            A Clipper Function Library
  20.   
  21.                                   Version 1.00
  22.                                     10/21/87
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.             Copyright (c)  Advanced Computer Consultants, Inc.  1987
  51.                                  P.O. Box 462
  52.                              Ridgeland, MS  39158
  53.  
  54.  
  55.  
  56.  
  57.  
  58.                                ACCI86.LIB
  59.                             TABLE OF CONTENTS
  60.  
  61.  
  62.  
  63.      Page       Contents
  64.  
  65.        1 ...... License
  66.        2 ...... Warranty
  67.        3 ...... Registration Order Form
  68.        4 ...... Overview
  69.  
  70.  
  71.                 Chapter 1    File Open/Close Functions
  72.  
  73.        6 ...... AC_OPEN()    - Allows setting of sharing and access mode
  74.        7 ...... AC_FOPEN()   - opens file with Deny None mode and 
  75.                                   Read/Write access as default
  76.                 AC_CREAT()   - allow setting of file attributes
  77.                 AC_FCREA()   - creates file with default attribute
  78.        8 ...... AC_CLOSE()   - closes an open file
  79.                 AC_UNIQ()    - create unique file using INT 5A
  80.  
  81.  
  82.                 Chapter 2    File I/O Functions (read and write)
  83.  
  84.        9 ...... AC_GETS()    - read string from file
  85.                 AC_PUTS()    - write string to file
  86.                 AC_GETB()    - read one byte as string from file
  87.       10 ...... AC_PUTB()    - write string as one byte to file
  88.                 AC_GETI()    - read integer from file
  89.                 AC_PUTI()    - write integer to file
  90.       11 ...... AC_GETD()    - read date from file
  91.                 AC_PUTD()    - write date to file
  92.                 AC_GETZ()    - read a ASCII 0 terminated string from file
  93.  
  94.  
  95.                 Chapter 3    File Pointer Functions
  96.  
  97.       12 ...... AC_MVPTR()   - move file pointer, all 3 modes
  98.                 AC_GOTOP()   - goto beginning of file
  99.                 AC_GOBOT()   - goto end of file
  100.       13 ...... AC_BOF()     - is BOF
  101.                 AC_EOF()     - is EOF
  102.                 AC_POSIN()   - current position
  103.       14 ...... AC_SKIP()    - move +- bytes
  104.                 AC_FSIZE()   - file length (size)
  105.  
  106.  
  107.  
  108.  
  109.      Page       Contents - Continued
  110.  
  111.  
  112.  
  113.                 Chapter 4    File Attribute Functions
  114.  
  115.       15 ...... AC_GATTR()   - read file attributes
  116.                 AC_ISRO()    - is read only file
  117.                 AC_ISHID()   - is a hidden file
  118.       16 ...... AC_ISSYS()   - is a system file
  119.                 AC_ISSUB()   - is a subdirectory
  120.                 AC_ISARC()   - is archive bit set
  121.       17 ...... AC_PATTR()   - write file attributes
  122.                 AC_MKRO()    - make file read only 
  123.                 AC_MKHID()   - make file hidden
  124.       18 ...... AC_MKSYS()   - make file system
  125.                 AC_MKARC()   - set archive bit 
  126.  
  127.  
  128.                 Chapter 5    File Time/Date Stamp Functions()
  129.  
  130.       19 ...... AC_GTIME()   - read file time stamp
  131.                 AC_GDATE()   - read file date stamp
  132.                 AC_PTIME()   - write file time stamp
  133.       20 ...... AC_PDATE()   - write file date stamp
  134.                 AC_PTD()     - write both time and date stamps
  135.  
  136.  
  137.                 Chapter 6    Misc. DOS Functions 
  138.  
  139.       21 ...... AC_QUIT()    - quit the program passing DOS an exit code
  140.                 AC_RETCD()   - get from DOS the exit code 
  141.                 AC_COMIT()   - Comit file using INT 68
  142.       22 ...... AC_DOS()     - returns the DOS version as a string
  143.  
  144.  
  145.                 Chapter 7    Other Functions
  146.  
  147.       23 ...... AC_DIAL()    - dial a given telephone number string
  148.                 AC_MODEM()   - set parameters for AC_DIAL()
  149.                 AC_SETM()    - also sets parameters for AC_DIAL()
  150.       24 ...... AC_STCL()    - set parameters on the constant display clock
  151.                 AC_CLSET()   - simpler method to set the clock
  152.       25 ...... AC_CLON()    - turn on the constant display clock
  153.                 AC_CLOFF()   - turn off the constant display clock
  154.  
  155.  
  156.  
  157.  
  158.      Page       Contents - Continued
  159.  
  160.  
  161.  
  162.                 Chapter 8    Error Recovery
  163.  
  164.       26 ...... OVERVIEW
  165.                 AC_ERROR()   - returns DOS or ACCI error number
  166.       27 ...... DOS ERROR CODES
  167.       29 ...... ACCI ERROR CODES
  168.  
  169.  
  170.                 Chapter 9    Standalone Utilities
  171.  
  172.       30 ...... FRMSTRUC     - prints the structure of a Report .FRM file
  173.  
  174.  
  175.                                   LICENSE
  176.  
  177.     "Programs" shall mean the computer software contained in the ACCI86.LIB
  178.     file and the accompanying documentation.
  179.  
  180.     The Programs are not in the public domain, nor are they free software.
  181.  
  182.     Copyright (C) 1987 ADVANCED COMPUTER CONSULTANTS, INC.  All rights
  183.     reserved.
  184.  
  185.     Non-registered users are granted a limited license to use the Programs 
  186.     on a trial basis for the purpose of determining whether the Programs
  187.     are suitable for their needs.  Use of the Programs, except for this 
  188.     limited purpose, requires registration.  Use of non-registered copies 
  189.     of the Programs by any person, business, corporation, governmental 
  190.     agency or other entity is strictly prohibited.
  191.  
  192.     All users are granted a limited license to copy the Programs only for the
  193.     trial use of others subject to the above limitations, and also the
  194.     following:
  195.  
  196.         - The Programs must be copied in unmodified form, complete with 
  197.           the file containing this license information.
  198.  
  199.         - The full ACCI86.LIB documentation must be included with the copy.
  200.  
  201.         - No fee, charge or other compensation may be accepted or requested
  202.           by any licensee.
  203.  
  204.     Operators of electronic bulletin board systems (Sysops) may post 
  205.     ACCI86.LIB for downloading by their users only as long as the above 
  206.     conditions are met.
  207.  
  208.     Registration grants a user the following non-exclusive privileges:
  209.         - You may incorporate any of the Programs into software applications
  210.           you develop.
  211.         - You may modify the Programs for the purpose of incorporating
  212.           them into your applications.
  213.         - You may distribute copies of the Programs to the extent they are
  214.           incorporated in your software applications and you have placed
  215.           your own copyright notice on the application.
  216.         - To incorporate the Programs into your application your application
  217.           can not be a library of functions as are the Programs.
  218.         - You may use the Programs as a library on only a single computer
  219.           at one time.  You are not limited by this license as to how many
  220.           copies of your applications incorporating the Programs you may
  221.           distribute.
  222.         - You may purchase for an additional amount a copy of the assembler
  223.           and Clipper source code. (See order form.)
  224.         - The Programs remain the property of ADVANCED COMPUTER CONSULTANTS,
  225.           INC. No amount of modification of the source or rewriting of the
  226.           source code will allow you to consider the resultant source code
  227.           to be your property.
  228.         - Notification of upgrades.
  229.  
  230.     See the registration form for more information on registration, quantity
  231.     purchases and similar topics.
  232.  
  233.                                     - 1 -
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.                                   WARRANTY
  243.  
  244.  
  245.     ADVANCED COMPUTER CONSULTANTS, INC. will replace any disks found to be 
  246.     physically defective within 30 days from date of purchase.
  247.  
  248.     ADVANCED COMPUTER CONSULTANTS, INC. warrants that the Programs will
  249.     perform in substantial compliance with the documentation supplied with 
  250.     the product.  If a significant defect in the product is found, 
  251.     Purchaser will be entitled to a refund.  In no event will such a refund 
  252.     exceed the purchase price of the Programs.
  253.  
  254.     EXCEPT AS PROVIDED ABOVE, ADVANCED COMPUTER CONSULTANTS, INC. DISCLAIMS
  255.     ALL WARRANTIES, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED 
  256.     TO IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
  257.     PURPOSE, WITH RESPECT TO THE PRODUCT.  SHOULD THE PROGRAMS PROVE TO BE 
  258.     DEFECTIVE, THE PURCHASER ASSUMES THE RISK OF PAYING THE ENTIRE COST OF 
  259.     ALL NECESSARY SERVICING, REPAIR, OR CORRECTION AND ANY INCIDENTAL OR 
  260.     CONSEQUENTIAL DAMAGES.  IN NO EVENT WILL ADVANCED COMPUTER CONSULTANTS, 
  261.     INC. BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING WITHOUT LIMITATION 
  262.     DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF 
  263.     BUSINESS INFORMATION AND THE LIKE) ARISING OUT OF THE USE OF OR 
  264.     INABILITY TO USE THIS PRODUCT EVEN IF ADVANCED COMPUTER CONSULTANTS, INC. 
  265.     HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  266.  
  267.     Use of this software product for any period of time constitutes your
  268.     assumed acceptance of this agreement and subjects you to it's contents.
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.                                     - 2 -
  293.                           REGISTRATION ORDER FORM
  294.  
  295.                       ADVANCED COMPUTER CONSULTANTS, INC. 
  296.                                  P.O. Box 462
  297.                              Ridgeland, MS 39158
  298.  
  299.  
  300.      Registration costs $25. for first copy..... _____ @ $25. = __________
  301.  
  302.               $20. for 2nd thru 10th copies..... _____ @ $20. = __________
  303.  
  304.               $15. for 11th and up copies....... _____ @ $15. = __________
  305.  
  306.                            Registration Totals   _____         $__________
  307.  
  308.      Registration does not include a diskette.  Diskettes containing the
  309.      ACCI86.LIB, documentation, compiled standalone utilities, ect. may
  310.      be purchased separately for $10. each.
  311.  
  312.                            Library diskettes.... _____ @ $10. = __________
  313.  
  314.      Copies of the Assembler and Clipper Source Code may be purchased 
  315.      separately by registered users.  Prices include a diskette containing 
  316.      all of the source code and the contents of the Library diskette above.
  317.  
  318.       Source Code costs $25. for first copy..... _____ @ $25. = __________
  319.  
  320.               $20. for 2nd thru 10th copies..... _____ @ $20. = __________
  321.  
  322.               $15. for 11th and up copies....... _____ @ $15. = __________
  323.  
  324.                             Source Code Totals   _____         $__________
  325.  
  326.              Clipper version________________      Total Order  $__________
  327.  
  328.              Diskette: 5 1/4_____ 3 1/2_____ 
  329.  
  330.              Quantity orders good only with that order, not cumulative
  331.              over several orders.  Check, cash, or money order only.
  332.              U.S. funds only.  
  333.  
  334.  
  335.              NAME ________________________________________________
  336.  
  337.              COMPANY _____________________________________________
  338.  
  339.              ADDRESS _____________________________________________
  340.  
  341.              _____________________________________________________
  342.  
  343.              CITY ___________________ STATE _____ ZIP ____________
  344.  
  345.  
  346.                  Upgrade notice sent to: (circle one of the below)
  347.  
  348.                             Source     - ID __________
  349.                             CompuServe - _____________
  350.                             Mail to above address
  351.                                     - 3 -
  352.  
  353.  
  354.  
  355.                                  OVERVIEW
  356.                                of ACCI86.LIB
  357.  
  358.  
  359.      Since this product is being distributed as "shareware" you have
  360.      no doubt deduced that this is a part time project for me.  My
  361.      full time job is as an analyst/programmer and 95% of my code is
  362.      compiled with Clipper.  What I am able to do for support is stated
  363.      below.  Please send to me descriptions of any "bugs" you may find
  364.      in this library.  Also, please send to me any ideas or needs you
  365.      have for additional functions.  I am able to do some custom 
  366.      programming for a fee, write for details.  
  367.  
  368.      SUPPORT POLICY:  Support provided to Registered Users only.  
  369.      Send to me complete descriptions of any problems you are having with 
  370.      this library, including a small portion of your code containing the 
  371.      offending function.  Include your name, company name, address, 
  372.      telephone number, and Registration Serial Number and I will respond 
  373.      as soon as I can.  Please do not call.  Send to one of the following 
  374.      mail boxes:
  375.  
  376.                           Source:     ID  BBV301
  377.                           CompuServe: 70701,2755
  378.  
  379.                      ADVANCED COMPUTER CONSULTANTS, INC.
  380.                                P.O. Box 462        
  381.                            Ridgeland, MS 39158
  382.  
  383.     UPGRADE POLICY:  I will send a notice to all Registered Users 
  384.     whenever there is a major upgrade to this library.  There may or
  385.     may not be an additional fee for the upgrade.  I may also notify
  386.     you of other products that I develop which may be of interest to
  387.     Clipper programmers.
  388.  
  389.  
  390.               Trademark Notice
  391.     DOS, IBM is a trademark of International Business Machines
  392.     Clipper is a trademark of Nantucket Corporation
  393.     dBASE and dBASE III Plus are trademarks of Ashton-Tate
  394.     Tom Rettig's Library is a trademark of Tom Rettig Associates
  395.  
  396.  
  397.     How to Link.  Name the ACCI86.LIB after the CLIPPER.LIB in linking
  398.     your program.
  399.  
  400.     Compatable with Autumn 86 version of Clipper.
  401.     The functions marked (DBF) would have to be recompiled to work with
  402.     the Winter 85 version of Clipper.  The assembly functions should work
  403.     ok as is with Winter 85 although I have not tested it.
  404.     I will make any necessary changes to make this library compatable with 
  405.     Summer 87 when it becomes available.  When ordering library diskettes
  406.     please state the version of Clipper you are using and I will compile
  407.     the Clipper code for you with that version.
  408.  
  409.  
  410.                                     - 4 -
  411.  
  412.  
  413.                              DOS FILE HANDLES
  414.  
  415.     Many of these functions use "file handles".  A file handle is one way
  416.     DOS keeps track of which file you are referring to when you execute DOS
  417.     functions.  When a file is opened with any of the Open Functions in
  418.     Chapter 1 a numeric file handle is returned by DOS and is returned
  419.     via the Open functions back to your Clipper program.  Save this handle
  420.     with a variable or in an array.  The functions in Chapters 2, 3,
  421.     and 5 all require the handle as a parameter.  DOS predefines five
  422.     standard device handles, you may use (with care) these handles also.
  423.  
  424.                Handle              Use           DOS Device
  425.                  0     Standard input device        CON:
  426.                  1     Standard output device       CON:
  427.                  2     Standard error device        CON:
  428.                  3     Standard auxiliary device    AUX:
  429.                  4     Standard printer device      LPT1: or PRN:
  430.  
  431.     DOS has an internal file pointer associated with each handle.  All
  432.     of the File I/O functions in Chapter 2 and many of the File Pointer
  433.     functions in Chapter 3 move this pointer.  During file I/O the
  434.     pointer is left pointing to the last byte read or written, and unless
  435.     you move the pointer, the next I/O function will begin with the next
  436.     byte.
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.                                     - 5 -
  470.  
  471.  
  472.  
  473.                                 CHAPTER  1
  474.                         File Open/Close Functions
  475.  
  476.  
  477.  
  478.     FUNCTION:   AC_OPEN()                (ASM)
  479.  
  480.  
  481.     This function opens a file.  The file is left open so that it 
  482.     can be processed.
  483.  
  484.     Syntax:     AC_OPEN( expC1 , expC2 )
  485.     Parameters: expC1 = <drive><path>file_name
  486.                 expC2 = the open mode as a 8 char bit string
  487.     Return:     the file handle as an integer, if successful, -1 if not
  488.  
  489.     Examples:   Handle = AC_OPEN('C:\apps\travel.fil','10010010')
  490.  
  491.                 M_file = 'Payroll'
  492.                 M_mode = '10100010'    && private, deny write, read/write
  493.                 Handle = AC_OPEN(M_file,M_mode)
  494.  
  495.  
  496.                               OPEN MODE BITS
  497.  
  498.                           bit  7  -  inheritance bit
  499.                      
  500.                    0 =  file is inherited by child process
  501.                    1 =  file is private to the current process
  502.  
  503.                        bits  6, 5, 4  -  sharing mode bits
  504.   (defines what access others can have to this file after you have opened it)
  505.  
  506.                           000 =  compatibility mode
  507.                           001 =  deny read/write (use exclusive)
  508.                           010 =  deny write
  509.                           011 =  deny read
  510.                           100 =  deny none
  511.  
  512.                           bit  3  -  reserved
  513.                             0 =  always cleared 
  514.  
  515.                        bits  2, 1, 0  -  access mode bits
  516.            (defines what access you can have to the file after opened)
  517.  
  518.                           000 =  read access
  519.                           001 =  write access
  520.                           010 =  read/write access
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.                                     - 6 - 
  529.  
  530.  
  531.  
  532.  
  533.  
  534.     FUNCTION:   AC_FOPEN()               (PRG)
  535.  
  536.  
  537.     Open a file with defaults - inherited, deny none sharing, read/write access
  538.  
  539.     Syntax:    AC_FOPEN( expC )
  540.     Parameter: expC = <drive><path>file_name
  541.     Return:    file handle if sucessful, -1 if failed
  542.  
  543.     Examples:  Handle = AC_FOPEN('\apps\acct_pay')
  544.  
  545.                M_file = 'info.dat'
  546.                Hands[1] = AC_FOPEN(M_file)
  547.  
  548.  
  549.  
  550.  
  551.     FUNCTION:   AC_CREAT()               (ASM)
  552.  
  553.  
  554.     This function creates and opens the passed file name for output. 
  555.     If the file exists, you specify if it is to be overwritten.  The 
  556.     file is left open so that it can be processed.  
  557.  
  558.           
  559.     Syntax:     AC_CREAT( expC1 , expL , expC2 )
  560.     Parameters: expC1 = <drive><path>file_name
  561.                 expL  = if .T. an existing file is overwritten,
  562.                         if .F. the function fails if the file exists.
  563.                 expC2 = the attribute as a binary string.
  564.     Return:     the file handle as an integer, if successful, -1 if not
  565.  
  566.     Example:    M_file = 'data.fil'
  567.                 Handle = AC_CREAT(M_file,.T.,'10100010')
  568.                          private, deny write, read/write
  569.  
  570.  
  571.  
  572.  
  573.     FUNCTION:   AC_FCREA()               (PRG)
  574.  
  575.  
  576.     Create a file with default attributes.
  577.  
  578.     Syntax:     handle = AC_FCREA( expC )
  579.     Parameter:  expC = <drive><path>file_name
  580.     Return:     file handle if sucessful, -1 if failed
  581.  
  582.     Example:    Handle = AC_FOPEN('\apps\acct_pay')
  583.  
  584.  
  585.  
  586.  
  587.                                     - 7 -
  588.  
  589.  
  590.  
  591.  
  592.  
  593.     FUNCTION:   AC_CLOSE()               (ASM)
  594.  
  595.  
  596.     This function closes the passed file handle.
  597.  
  598.     Syntax:     AC_CLOSE( expN )
  599.     Parameter:  expN = the handle saved from one of the four open functions
  600.     Return:     .T., if successful, .F. if not
  601.  
  602.     Example:    AC_CLOSE( Handle )
  603.  
  604.  
  605.  
  606.  
  607.     FUNCTION:   AC_UNIQ()                (ASM)
  608.  
  609.  
  610.     This function creates a file and determines the file's name
  611.     so that the file name is unique.  The file is closed and the file
  612.     name returned.
  613.  
  614.     Syntax:      AC_UNIQ( expC1 , expC2 )
  615.     Parameters:  expC1 = the file path terminated with a backslash '\'
  616.                  expC2 = the attribute as a bit string
  617.     Return:      the file \path\name, if successful, 'AC_ERROR', if failed
  618.  
  619.     Example:     File_name = AC_UNIQ('C:\appls\','10100010')
  620.                              private, deny write, read/write
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.                                     - 8 -
  647.  
  648.  
  649.  
  650.  
  651.                                 CHAPTER  2
  652.                             File I/O Functions
  653.  
  654.  
  655.  
  656.     FUNCTION:   AC_GETS()                (ASM)
  657.  
  658.  
  659.     This function reads a string from a file opened by AC_OPEN().  
  660.  
  661.     Syntax:     AC_GETS( expN1 , expN2 )
  662.     Parameters: expN1 = the number of bytes to read from 1 to a maxinum of 255
  663.                 expN2 = the file handle
  664.     Return:     file data as a string, or AC_ERROR if failed
  665.  
  666.     Examples:   M_string = AC_GETS(20,Handle)
  667.  
  668.                 Handle1 = AC_OPEN('hello.dat')
  669.                 Byte_ct = 15
  670.                 @ 10,20 SAY AC_GETS(Byte_ct,Handle1)
  671.  
  672.  
  673.  
  674.  
  675.     FUNCTION:   AC_PUTS()                (ASM)
  676.  
  677.  
  678.     This function writes a string to a file opened by AC_OPEN().  
  679.  
  680.     Syntax:     AC_PUTS( expN , expC )
  681.     Parameters: expN = the file handle
  682.                 expC = the string to write to disk
  683.     Return:     .T. if sucessfull, .F. if not
  684.  
  685.     Example:    Handle3 = AC_FCREA('data.fil')
  686.                 AC_PUTS( Handle3, 'Write this string to file.' )
  687.  
  688.  
  689.  
  690.  
  691.     FUNCTION:   AC_GETB()                (ASM)
  692.  
  693.  
  694.     This function returns a string containing 1s and 0s of the binary
  695.     pattern of the current byte (bit order 76543210 of string) from
  696.     a file opened by AC_OPEN().
  697.  
  698.     Syntax:     AC_GETB( expN )
  699.     Parameters: expN = the file handle
  700.     Return:     file data in a bit pattern of one byte in a char string,
  701.                 or 'AC_ERROR' if failed
  702.  
  703.     Example:    M_byte = AC_GETB( Handle )     && read a carriage return
  704.                 ? M_byte
  705.                 '00001101'
  706.                                     - 9 -
  707.  
  708.  
  709.  
  710.  
  711.     FUNCTION:   AC_PUTB()                (ASM)
  712.  
  713.  
  714.     This function receives a string containing 1s and 0s of the binary
  715.     pattern of the byte (bit order 76543210 of string) to write to
  716.     a file opened by AC_OPEN().
  717.  
  718.  
  719.     Syntax:     AC_PUTB( expN , expC )
  720.     Parameters: expN = the file handle
  721.                 expC = the string to convert into a byte
  722.     Return:     .T. if sucessful, .F. if failed
  723.  
  724.     Example:    AC_PUTB( Handle , '00001101' )   && write a carriage return
  725.  
  726.  
  727.  
  728.  
  729.     FUNCTION:   AC_GETI()                (ASM)
  730.  
  731.  
  732.     This function returns integer data from a file opened by AC_OPEN().  
  733.     The bytes are read least significant byte first.
  734.  
  735.     Syntax:     AC_GETI( expN1 , expN2 )
  736.     Parameters: expN1 = the file handle
  737.                 expN2 = number of bytes to read from 1 to a maximum of 4
  738.     Return:     file data of type integer if sucessful, -1 if failed
  739.                 (check AC_ERROR())
  740.  
  741.     Example:    M_integer = AC_GETI( Handle, 2 )
  742.  
  743.  
  744.  
  745.  
  746.     FUNCTION:   AC_PUTI()                (ASM)
  747.  
  748.  
  749.     This function writes integer data to a file opened by AC_OPEN().  
  750.     The bytes are written least significant byte first.
  751.  
  752.     Syntax:     AC_PUTI( expN1 , expN2 , expN3 )
  753.     Parameters: expN1 = the file handle
  754.                 expN2 = number of bytes to write from 1 to a maximum of 4
  755.                 expN3 = the integer to write to disk
  756.     Return:     .T. if sucessful, .F. if not
  757.  
  758.     Example:    AC_PUTI( Handle , 3 , 88000 )  
  759.                        && writes the number 88000 to disk in 3 bytes
  760.  
  761.  
  762.  
  763.  
  764.  
  765.                                     - 10 -
  766.  
  767.  
  768.  
  769.  
  770.     FUNCTION:   AC_GETD()                (ASM)
  771.  
  772.  
  773.     This function returns a date from a file opened by AC_OPEN().  
  774.     The date string in the file must be in the format 'YYYYMMDD'
  775.  
  776.     Syntax:     AC_GETD( expN )
  777.     Parameters: expN = the file handle
  778.     Return:     file data as a date if sucessful, an empty date if failed
  779.  
  780.     Example:    M_date = AC_GETD( Handle )
  781.                 ? TYPE('M_date')
  782.                 D
  783.  
  784.  
  785.  
  786.     FUNCTION:   AC_PUTD()                (ASM)
  787.  
  788.  
  789.     This function writes a date to a file opened by AC_OPEN().  
  790.     The date string is written to the file in the format 'YYYYMMDD'
  791.  
  792.     Syntax:     AC_PUTD( expN , expD )
  793.     Parameters: expN = the file handle
  794.                 expD = the date to write to disk
  795.     Return:     .T. if sucessfull, .F. if failed
  796.  
  797.     Example:    M_date = CTOD('10/10/87')
  798.                 AC_PUTD( Handle , M_date )
  799.  
  800.  
  801.  
  802.  
  803.     FUNCTION:   AC_GETZ()                (ASM)
  804.  
  805.  
  806.     This function returns a string from a file opened by AC_OPEN().  
  807.     Bytes are read from the file one byte at a time and tested for the
  808.     string terminator ASCII 0.  All bytes up to the string terminator
  809.     are returned.
  810.  
  811.     Syntax:     AC_GETZ( expN )
  812.     Parameters: expN = the file handle
  813.     Return:     file data as a string, or AC_ERROR if failed
  814.  
  815.     Examples:   M_string = AC_GETZ( Handle )
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.                                     - 11 -
  825.  
  826.  
  827.  
  828.  
  829.                                 CHAPTER  3
  830.                           File Pointer Functions
  831.  
  832.  
  833.     FUNCTION:   AC_MVPTR()               (ASM)
  834.  
  835.  
  836.     This function moves the file pointer in a file opened by AC_OPEN().  
  837.  
  838.     Syntax:     AC_MVPTR( expN1 , expN2 , expN3 )
  839.     Parameters: expN1 = the file handle
  840.                 expN2 = MODE
  841.                 expN3 = number of bytes to move
  842.     Return:     new pointer location in relation to the beginning of the file,
  843.                 -1 if failed
  844.  
  845.      MODE:  0 = from beginning of file
  846.             1 = from current position
  847.             2 = from end of file
  848.  
  849.     Examples:   top_of_file = AC_MVPTR( Handle, 0, 0 )
  850.                 end_of_file = AC_MVPTR( Handle, 2, 0 )
  851.                 skip_10     = AC_MVPTR( Handle, 1, 10 )
  852.  
  853.  
  854.  
  855.  
  856.     FUNCTION:   AC_GOTOP()               (PRG)
  857.  
  858.  
  859.     Moves the file pointer to the top of the file (offset 0).
  860.  
  861.     Syntax:    AC_GOTOP( expN )
  862.     Parameter: file handle
  863.     Return:    .T. if sucessful, .F. if failed
  864.  
  865.     Example:   AC_GOTOP( Handle )
  866.  
  867.  
  868.  
  869.  
  870.     FUNCTION:   AC_GOBOT()               (PRG)
  871.  
  872.  
  873.     Moves the file pointer to the bottom (end) of the file.
  874.  
  875.     Syntax:    AC_GOBOT( expN )
  876.     Parameter: file handle
  877.     Return:    .T. if sucessful, .F. if failed
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.                                     - 12 -
  885.  
  886.  
  887.  
  888.  
  889.     FUNCTION:   AC_BOF()                 (PRG)
  890.  
  891.  
  892.     Checks to see if the pointer is at the beginning of the file (offset 0).
  893.  
  894.     Syntax:    AC_BOF( expN )
  895.     Parameter: file handle
  896.     Return:    .T. if pointer is at beginning of the file, .F. if not
  897.  
  898.     Example:   AC_BOF( Handle )
  899.  
  900.  
  901.  
  902.  
  903.     FUNCTION:   AC_EOF()                 (PRG)
  904.  
  905.  
  906.     Checks to see if the pointer is at the end of the file.
  907.  
  908.     Syntax:    AC_EOF( expN )
  909.     Parameter: file handle
  910.     Return:    .T. if the pointer is at the end of the file, .F. if not
  911.  
  912.     Example:   AC_EOF( Handle )
  913.  
  914.  
  915.  
  916.  
  917.     FUNCTION:   AC_POSIN()               (PRG)
  918.  
  919.  
  920.     Returns the position of the pointer in bytes from the beginning of 
  921.     the file.
  922.  
  923.     Syntax:    AC_POSIN( expN )
  924.     Parameter: file handle
  925.     Return:    offset from beginning of file, -1 if failed
  926.  
  927.     Example:   AC_POSIN( Handle )
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.                                     - 13 -
  944.  
  945.  
  946.  
  947.  
  948.     FUNCTION:   AC_SKIP()                (PRG)
  949.  
  950.  
  951.     Moves the file pointer forward (or backward if negative) the input
  952.     number of bytes.
  953.  
  954.     Syntax:    AC_SKIP( expN1 , expN2 )
  955.     Parameter: expN1 = file handle
  956.                expN2 = number of bytes to skip + or -
  957.     Return:    offset from beginning of file, -1 if failed
  958.  
  959.     Example:   AC_GOTOP( Handle )
  960.                M_offset = AC_SKIP( Handle , 25 )
  961.                ? M_offset
  962.                25
  963.  
  964.  
  965.  
  966.  
  967.     FUNCTION:   AC_FSIZE()               (PRG)
  968.  
  969.  
  970.     Returns the file length (size) in bytes.
  971.  
  972.     Syntax:    AC_FSIZE( expN )
  973.     Parameter: file handle
  974.     Return:    length of file, same as file size with DOS DIR command,
  975.                -1 if failed
  976.  
  977.     Examples:  M_len = AC_FSIZE( Handle )
  978.  
  979.                Handle = AC_OPEN('data.ext')
  980.                M_len  = AC_FSIZE( Handle )   && M_len contains lenth of file
  981.                AC_CLOSE( Handle )
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.  
  1002.                                     - 14 -
  1003.  
  1004.  
  1005.  
  1006.                                 CHAPTER  4
  1007.                          File Attribute Functions
  1008.  
  1009.  
  1010.     FUNCTION:   AC_GATTR()               (ASM)
  1011.  
  1012.  
  1013.     This function returns the attribute of the passed file name.
  1014.  
  1015.     Syntax:    AC_GATTR( expC )
  1016.     Parameter: expC = <drive><path>file_name
  1017.     Return:    A char string made of 1s and 0s in the bit pattern 
  1018.                of the file's attribute byte, 'AC_ERROR' if failed
  1019.  
  1020.     Example:   M_attr = AC_GATTR( 'C:\apps\password.dbf' )
  1021.  
  1022.                   bit pattern '76543210'
  1023.                   bit 0 -  '1' = read only
  1024.                   bit 1 -  '1' = hidden file
  1025.                   bit 2 -  '1' = system file
  1026.                   bit 3 -  '1' = volume lable
  1027.                   bit 4 -  '1' = subdirectory
  1028.                   bit 5 -  '1' = archive
  1029.                   bit 6 -  '0' = undefined (must be 0)
  1030.                   bit 7 -  '0' = undefined (must be 0)
  1031.  
  1032.  
  1033.  
  1034.  
  1035.     FUNCTION:   AC_ISRO()                (PRG)
  1036.  
  1037.  
  1038.     Test to see if the file is Read Only.
  1039.  
  1040.     Syntax:    AC_ISRO( expC )
  1041.     Parameter: expC = <drive><path>file_name
  1042.     Return:    .T. if file is read only, .F. if file is not read only
  1043.  
  1044.     Example:   Read_stat = AC_ISRO( '\apps\payroll.dbf' )
  1045.  
  1046.  
  1047.     FUNCTION:   AC_ISHID()               (PRG)
  1048.  
  1049.  
  1050.     Tests to see if the file is hidden.
  1051.  
  1052.     Syntax:    AC_ISHID( expC )
  1053.     Parameter: expC = <drive><path>file_name
  1054.     Return:    .T. if file is hidden, .F. if file is not hidden
  1055.  
  1056.     Example:   Hid_stat = AC_ISHID( '\apps\payroll.dbf' )
  1057.  
  1058.  
  1059.  
  1060.  
  1061.                                     - 15 -
  1062.  
  1063.  
  1064.  
  1065.  
  1066.     FUNCTION:   AC_ISSYS()               (PRG)
  1067.  
  1068.  
  1069.     Tests to see if the file is a system file.
  1070.  
  1071.     Syntax:    AC_ISSYS( expC )
  1072.     Parameter: expC = <drive><path>file_name
  1073.     Return:    .T. if file is a system file, .F. if file is not a system file
  1074.  
  1075.     Example:   Sys_stat = AC_ISSYS( '\apps\payroll.dbf' )
  1076.  
  1077.  
  1078.  
  1079.  
  1080.     FUNCTION:   AC_ISSUB()               (PRG)
  1081.  
  1082.  
  1083.     Tests to see if the file is a subdirectory.
  1084.  
  1085.     Syntax:    AC_ISSUB( expC )
  1086.     Parameter: expC = <drive><path>file_name
  1087.     Return:    .T. if file is a subdirectory, .F. if file is not a subdirectory
  1088.  
  1089.     Example:   Sub_stat = AC_ISSUB( '\apps\payroll.dbf' )
  1090.  
  1091.  
  1092.  
  1093.  
  1094.     FUNCTION:   AC_ISARC()               (PRG)
  1095.  
  1096.  
  1097.     Tests to see if the file has archive bit set.
  1098.  
  1099.     Syntax:    AC_ISARC( expC )
  1100.     Parameter: expC = <drive><path>file_name
  1101.     Return:    .T. if file archive bit set, .F. if file archive bit is not set
  1102.  
  1103.     Example:   Arc_stat = AC_ISARC( '\apps\payroll.dbf' )
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.                                     - 16 -
  1121.  
  1122.  
  1123.  
  1124.  
  1125.     FUNCTION:   AC_PATTR()               (ASM)
  1126.  
  1127.  
  1128.     This function changes the attribute of the passed file name.
  1129.     
  1130.  
  1131.     Syntax:     AC_PATTR( expC1 , expC2 )
  1132.     Parameters: expC1 = <drive><path>file_name
  1133.                 expC2 = a char string made of 1s and 0s in the bit pattern 
  1134.                         of the attribute byte
  1135.     Return:     .T. if successful, .F. if failed
  1136.  
  1137.     Example:   AC_PATTR( 'C:\apps\password.dbf' , '00000011' )
  1138.                      && make file read only and hidden
  1139.  
  1140.  
  1141.  
  1142.  
  1143.     FUNCTION:   AC_MKRO()                (PRG)
  1144.    
  1145.  
  1146.     Makes the file read only.
  1147.  
  1148.     Syntax:     AC_MKRO( expC , expL )
  1149.     Parameters: expC = <drive><path>file_name
  1150.                 expL = .T. to make read only, .F. to not make read only
  1151.     Return:    .T. if sucessful, .F. if not sucessful
  1152.  
  1153.     Example:   AC_MKRO( 'password.dbf' , .T. )  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.     FUNCTION:   AC_MKHID()               (PRG)
  1159.  
  1160.  
  1161.     Makes the file hidden.
  1162.  
  1163.     Syntax:     AC_MKHID( expC , expL )
  1164.     Parameters: expC = <drive><path>file_name
  1165.                 expL = .T. to make hidden, .F. to make regular (un-hidden)
  1166.     Return:    .T. if sucessful, .F. if not sucessful
  1167.  
  1168.     Example:   AC_MKHID( 'password.dbf' , .T. )  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.                                     - 17 -
  1180.  
  1181.  
  1182.  
  1183.  
  1184.     FUNCTION:   AC_MKSYS()               (PRG)
  1185.  
  1186.  
  1187.     Makes the file a system file.
  1188.  
  1189.     Syntax:     AC_MKSYS( expC , expL )
  1190.     Parameters: expC = <drive><path>file_name
  1191.                 expL = .T. to make system file, .F. to make not system
  1192.     Return:     .T. if sucessful, .F. if not sucessful
  1193.  
  1194.     Example:    AC_MKSYS( 'file.dat' , .F. )  
  1195.  
  1196.  
  1197.  
  1198.  
  1199.     FUNCTION:   AC_MKARC()               (PRG)
  1200.  
  1201.  
  1202.     Sets the archive bit in the file.
  1203.  
  1204.     Syntax:     AC_MKARC( expC , expL )
  1205.     Parameters: expC = <drive><path>file_name
  1206.                 expL = .T. to set archive bit, .F. to clear archive bit
  1207.     Return:    .T. if sucessful, .F. if not sucessful
  1208.  
  1209.     Example:    AC_MKARC( 'password.dbf' , .F. )  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.                                     - 18 -
  1239.  
  1240.  
  1241.  
  1242.                                 CHAPTER  5
  1243.                       File Time/Date Stamp Functions
  1244.  
  1245.  
  1246.     FUNCTION:   AC_GTIME()               (ASM)
  1247.  
  1248.  
  1249.     This function returns the file stamp time from a file.
  1250.  
  1251.     Syntax:    AC_GTIME( expN )
  1252.     Parameter: expN = file handle
  1253.     Return:    file time stamp as a char string, 'AC_ERROR' if failed
  1254.  
  1255.     Example:   M_time = AC_GTIME( Handle )
  1256.  
  1257.  
  1258.  
  1259.  
  1260.     FUNCTION:   AC_GDATE()               (ASM)
  1261.  
  1262.  
  1263.     This function returns the file date stamp from a file.
  1264.  
  1265.     Syntax:    AC_GDATE( expN )
  1266.     Parameter: expN = file handle
  1267.     Return:    file date stamp as a date type, an empty date if failed
  1268.  
  1269.     Example:   M_date = AC_GDATE( Handle )
  1270.                ? TYPE( 'M_date' )
  1271.                D
  1272.  
  1273.  
  1274.  
  1275.  
  1276.     FUNCTION:   AC_PTIME()               (ASM)
  1277.  
  1278.  
  1279.     This function sets the file stamp time in a file.
  1280.  
  1281.     Syntax:     AC_PTIME( expN , expC )
  1282.     Parameters: expN = file handle
  1283.                 expC = time string in the format 'hh:mm:ss'
  1284.                        The seconds should be even.
  1285.     Return:     .T. if successful, .F. if failed
  1286.  
  1287.     Example:    AC_PTIME( Handle , '12:30:00' )  && sets time as 12:30 pm
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.                                     - 19 -
  1298.  
  1299.  
  1300.  
  1301.  
  1302.     FUNCTION:   AC_PDATE()               (ASM)
  1303.  
  1304.  
  1305.     This function sets the file stamp date in a file.  The earliest
  1306.     possible date is 01/01/1980.  The latest possible date is 12/31/2099.
  1307.  
  1308.     Syntax:     AC_PDATE( expN , expD )
  1309.     Parameters: expN = file handle
  1310.                 expD = date as a date type
  1311.     Return:     .T. if successful, .F. if failed
  1312.  
  1313.     Example:    AC_PDATE( Handle , CTOD('10/10/87') )
  1314.  
  1315.  
  1316.  
  1317.  
  1318.     FUNCTION    AC_PTD()                 (PRG)
  1319.  
  1320.  
  1321.     This function changes both a files date and time stamps.
  1322.  
  1323.     Syntax:    AC_FTD( expC1 , expD , expC2 )
  1324.     Parameter: expC1 = <drive><path>file_name
  1325.                expD  = date as a date type
  1326.                        range from 01/01/1980 to 12/31/2099
  1327.                expC2 = time string in the format 'hh:mm:ss'
  1328.                        The seconds should be even.
  1329.  
  1330.     Return:    .T. if sucessful, .F. if failed
  1331.  
  1332.     Example:   AC_PTD( 'test.fil' , CTOD('10/18/87') , '10:10:30' )
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.                                     - 20 -
  1357.  
  1358.  
  1359.  
  1360.                                 CHAPTER  6
  1361.                             Misc. DOS Functions
  1362.  
  1363.  
  1364.     FUNCTION:   AC_QUIT()                (ASM)
  1365.  
  1366.  
  1367.     This function terminates the Clipper compiled application and returns 
  1368.     the passed return code. The parameter is the return code. You must
  1369.     close all databases, and files opened with the ACCI86.LIB with the
  1370.     appropriate commands.  This function DOES NOT CLOSE ANY FILES!!!
  1371.     You can test the passed return code at the DOS level with the batch
  1372.     command ERRORLEVEL.
  1373.  
  1374.  
  1375.     Syntax:    AC_QUIT( expN )
  1376.     Parameter: the return code as an integer, range from 1 to 255
  1377.     Return:    .F. if fails to terminate the application
  1378.  
  1379.     Example:   AC_QUIT(1)
  1380.                
  1381.  
  1382.  
  1383.  
  1384.     FUNCTION:   AC_RETCD()               (ASM)
  1385.  
  1386.  
  1387.     This function returns as an integer the return code of a terminated 
  1388.     subprocess. This function must be called immediately after the process
  1389.     terminates.  
  1390.  
  1391.     Syntax:    AC_RETCD()
  1392.     Parameter: none
  1393.     Return:    return code of type integer, -1 if failed
  1394.  
  1395.     Example:   ret_code = AC_RETCD()
  1396.  
  1397.  
  1398.  
  1399.  
  1400.     FUNCTION:   AC_COMIT()               (ASM)
  1401.  
  1402.  
  1403.     This function causes all DOS file buffered data to be written to disk.
  1404.     This function may only be used with DOS version 3.3 or higher.
  1405.     The parameter is the file handle.
  1406.  
  1407.     Syntax:    AC_COMIT( expN )
  1408.     Parameter: the file handle
  1409.     Return:    .T. if successful, .F. if failed
  1410.  
  1411.     Example:   AC_COMIT( Handle )
  1412.  
  1413.  
  1414.  
  1415.                                     - 21 -
  1416.  
  1417.  
  1418.  
  1419.     FUNCTION:   AC_DOS()                 (ASM)
  1420.  
  1421.  
  1422.     This function returns the DOS version as a string in the format '3.30'.
  1423.     There is no parameter.
  1424.  
  1425.     Syntax:    AC_DOS()
  1426.     Parameter: none
  1427.     Return:    DOS version as a string in the format '3.30',
  1428.                'AC_ERROR' if failed
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.  
  1465.  
  1466.  
  1467.  
  1468.  
  1469.  
  1470.  
  1471.  
  1472.  
  1473.  
  1474.                                     - 22 -
  1475.  
  1476.  
  1477.  
  1478.                                 CHAPTER  7
  1479.                              Other Functions
  1480.  
  1481.  
  1482.     FUNCTION:   AC_DIAL()                (ASM)
  1483.  
  1484.  
  1485.     This function dials the input telephone number on an attached Hayes
  1486.     compatable modem.
  1487.  
  1488.     Syntax:     AC_DIAL( expC )
  1489.     Parameters: expC = a char string of the telephone number to dial
  1490.     Return:     .T. if sucessful, .F. if failed
  1491.  
  1492.     Example:    AC_DIAL('601,555-1212')
  1493.  
  1494.                 Phone_no = '812,555-1212'
  1495.                 AC_DIAL( Phone_no )
  1496.  
  1497.  
  1498.  
  1499.  
  1500.     FUNCTION:   AC_MODEM()               (ASM)
  1501.  
  1502.  
  1503.     This function sets the modem settings for use with the AC_DIAL() function.
  1504.     I recommend that you use AC_SETM(). 
  1505.  
  1506.     Syntax:     AC_MODEM( expN1 , expN2 , expC )
  1507.     Parameters: expN1 = COM port
  1508.                 expN2 = initstr
  1509.                 expC  = dial type  ( T = touchtone,  P = pulse dial )
  1510.     Return:     .T. if sucessful, .F. if failed
  1511.  
  1512.  
  1513.  
  1514.  
  1515.     FUNCTION:   AC_SETM()                (PRG)
  1516.  
  1517.  
  1518.     Sets the modem parameters by creating the initstr used by AC_MODEM().
  1519.  
  1520.     Syntax:     AC_SETP( expN1 , expN2 , expC1 , expN3 , expN4 , expC2 )
  1521.     Parameters: expN1 = COM port -  1 or 2
  1522.                 expN2 = BAUD rate - 300, 1200, 2400
  1523.                 expC1 = Parity - E(ven), O(dd), N(one)
  1524.                 expN3 = Word length - 7 or 8
  1525.                 expN4 = Stop Bits - 1 or 2
  1526.                 expC2 = Dial type - T = touchtone, P = pulse dial
  1527.     Return:     .T. if sucessfull, .F. if failure
  1528.  
  1529.     Example:    AC_SETP( 2, 1200, 'N', 8, 1, 'P' )
  1530.  
  1531.  
  1532.  
  1533.                                     - 23 -
  1534.  
  1535.  
  1536.  
  1537.  
  1538.     The clock functions are used to set, turn on, turn off and display
  1539.     a constant display clock showing date, time, and day of week. Also 
  1540.     displayed are the Caps Lock and Num Lock states.  This function
  1541.     is an an interrupt which is chained onto interrupt 1Ch.  If you turn
  1542.     on the display with AC_CLON() and exit the program (as by Quit at an
  1543.     error) without calling AC_CLOFF(), then your computer will hang.
  1544.     For this reason I recommend that you only use these functions after
  1545.     your program is fully debuged.  The display is performed through
  1546.     direct writes to the screen buffer, this is faster.
  1547.  
  1548.  
  1549.  
  1550.  
  1551.     FUNCTION:   AC_CLSET()               (ASM)
  1552.  
  1553.  
  1554.     This function sets the parameters for the time/date continuous display.
  1555.     This function must be called before CLOCKON().
  1556.     This function should only be called when CLOCKOFF() (continuous display
  1557.          is disabled.)
  1558.     All three parameters must be present.
  1559.  
  1560.     Syntax:     AC_CLSET( expN1 , expN2 , expC )
  1561.     Parameters: expN1 = Type of monitor,  1 = Monochrome,  2 = Color
  1562.                 expN2 = Day of week <numeric>
  1563.                 expC  = Date string of the current date '10-Oct-87'
  1564.     Return:    .T. if successful, .F. if not
  1565.     
  1566.     Example:   see AC_STCL()
  1567.  
  1568.  
  1569.  
  1570.  
  1571.     FUNCTION:   AC_STCL()                (PRG)
  1572.  
  1573.  
  1574.     The best way to set the parameters for the constant display clock.
  1575.  
  1576.     Syntax:     AC_STCL()
  1577.     Parameters: none
  1578.     Return:     .T. if sucessful, .F. if failed
  1579.  
  1580.     The following is the code for AC_STCL
  1581.  
  1582.     FUNCTION AC_STCL
  1583.     Date_str = STR(DAY(DATE()),2,0) + '-' + SUBSTR(CMONTH(DATE()),1,3) ;
  1584.                + '-' + STR(YEAR(DATE())-1900,2,0)
  1585.     Monitor = IF(ISCOLOR(),2,1)
  1586.     RETURN AC_CLSET(Monitor,DOW(DATE()),Date_str)
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.                                     - 24 -
  1593.  
  1594.  
  1595.  
  1596.  
  1597.     FUNCTION:   AC_CLON()                (ASM)
  1598.  
  1599.  
  1600.     This function enables the time/date continuous display.
  1601.  
  1602.     Syntax:     AC_CLON()
  1603.     Parameters: none
  1604.     Return:     .T. if sucessful, .F. if not 
  1605.  
  1606.     RECOMENDED PROGRAMMING:
  1607.  
  1608.     PUBLIC Clock_on
  1609.     IF AC_STCL()
  1610.        Clock_on = .T.   
  1611.        AC_CLON()
  1612.     ELSE
  1613.        Clock_on = .F.
  1614.     ENDIF
  1615.     
  1616.  
  1617.  
  1618.     FUNCTION:   AC_CLOFF()               (ASM)
  1619.  
  1620.  
  1621.     This function disables the time/date continuous display.
  1622.     THIS FUNCTION MUST BE CALLED BEFORE EXITING THE PROGRAM OR THE 
  1623.     COMPUTER WILL HANG.
  1624.  
  1625.     Syntax:     AC_CLOFF()
  1626.     Parameters: none
  1627.     Return:     .T. if sucessful, .F. if not 
  1628.  
  1629.     RECOMENDED PROGRAMMING:
  1630.  
  1631.     IF Clock_on       && see AC_CLON() example
  1632.        AC_CLOFF()
  1633.     ENDIF
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.                                     - 25 -
  1652.  
  1653.  
  1654.  
  1655.                                 CHAPTER  8
  1656.                               Error Recovery
  1657.  
  1658.  
  1659.     OVERVIEW - Most of the functions in this library will return data 
  1660.     that will indicate if an error has occured.  The type of the error 
  1661.     return provided depends on the type of "good" data returned.  The
  1662.     error indicators are listed below.
  1663.  
  1664.                File Handle = -1 indicates an error
  1665.                Char String = returns the message 'AC_ERROR'
  1666.                Numeric     = -1 or 0, see each function
  1667.                Logical     = returns .F. (false) on error
  1668.                Date        = and empty date indicates an error
  1669.  
  1670.     Your program can test for error conditions in two ways.  You can 
  1671.     perform the function and test for the appropriate error data listed
  1672.     above and/or you can test by performing the AC_ERROR() function.  
  1673.     This function returns a numeric error code.  Most of these error
  1674.     codes are the standard DOS error codes, however, a few represent
  1675.     error conditions specific to this library.
  1676.  
  1677.     Example 1:      M_handle = AC_OPEN('\apps\myfile',11000010')
  1678.                     IF M_handle = -1
  1679.                        .
  1680.                        . statements
  1681.                        .
  1682.                     ENDIF
  1683.  
  1684.     Example 2:      M_handle = AC_OPEN('\apps\myfile',11000010')
  1685.                     IF AC_ERROR() > 0
  1686.                        .
  1687.                        . statements
  1688.                        .
  1689.                     ENDIF
  1690.  
  1691.  
  1692.  
  1693.     FUNCTION:   AC_ERROR()               (ASM)
  1694.  
  1695.     Returns the error code if an error occured on the last AC_* function
  1696.     called.  If no error occured on the last AC_* function then 0 is
  1697.     returned.  See the error codes and their meaning listed below.
  1698.  
  1699.     Syntax:    AC_ERROR()
  1700.     Parameter: none
  1701.     Return:    the last error code generated by an AC_* function or 0
  1702.                if no error occured, this function can be called more than
  1703.                once until any other AC_* function is called again
  1704.  
  1705.     Example:   M_error = AC_ERROR()
  1706.  
  1707.  
  1708.  
  1709.  
  1710.                                     - 26 -
  1711.  
  1712.  
  1713.  
  1714.                              DOS ERROR CODES
  1715.  
  1716.             Code       Meaning
  1717.               1    - Invalid function number
  1718.               2    - File not found
  1719.               3    - Path not found
  1720.               4    - Too many files open (no handles left)
  1721.               5    - Access denied
  1722.               6    - Invalid handle
  1723.               7    - Memory control blocks destroyed
  1724.               8    - Insufficient memory
  1725.               9    - Invalid memory block address
  1726.              10    - Invalid environment
  1727.              11    - Invalid format
  1728.              12    - Invalid access code
  1729.              13    - Invalid data
  1730.              14    - Reserved
  1731.              15    - Invalid drive was specified
  1732.              16    - Attempt to remove the current directory
  1733.              17    - Not same device
  1734.              18    - No more files
  1735.              19    - Attempt to write on write-protected diskette
  1736.              20    - Unknown unit   
  1737.              21    - Drive not ready
  1738.              22    - Unknown command
  1739.              23    - Data error CRC
  1740.              24    - Bad request structure length
  1741.              25    - Seek error
  1742.              26    - Unknown media type
  1743.              27    - Sector not found
  1744.              28    - Printer out of paper
  1745.              29    - Write fault
  1746.              30    - Read fault
  1747.              31    - General failure
  1748.              32    - Sharing violation
  1749.              33    - Lock violation
  1750.              34    - Invalid disk change
  1751.              35    - FCB unavailable
  1752.              36    - Sharing buffer overflow
  1753.              37 - 49  - Reserved
  1754.              50    - Network request not supported
  1755.              51    - Remote computer not listening
  1756.              52    - Duplicate name on network
  1757.              53    - Network name not found
  1758.              54    - Network busy
  1759.              55    - Network device no longer exists
  1760.              56    - Net BIOS command limit exceeded
  1761.              57    - Network adapter hardware error
  1762.              58    - Incorrect response from network
  1763.              59    - Unexpected network error
  1764.              60    - Incompatible remote adapter
  1765.              61    - Print queue full
  1766.  
  1767.  
  1768.  
  1769.                                     - 27 -
  1770.  
  1771.  
  1772.  
  1773.                              DOS ERROR CODES - continued
  1774.  
  1775.             Code       Meaning
  1776.              62    - Not enough space for print file
  1777.              63    - Print file was deleted
  1778.              64    - Network name was deleted
  1779.              65    - Access denied
  1780.              66    - Network device type incorrect
  1781.              67    - Network name not found
  1782.              68    - Network name limit exceeded
  1783.              69    - Net BIOS session limit exceeded
  1784.              70    - Temporarily paused
  1785.              71    - Network request not accepted
  1786.              72    - Print or disk redirection is paused
  1787.              73 - 79  - Reserved
  1788.              80    - File exists
  1789.              81    - Reserved
  1790.              82    - Cannot make directory entry
  1791.              83    - Fail on INT 24
  1792.              84    - Too many redirections
  1793.              85    - Duplicate redirection
  1794.              86    - Invalid password
  1795.              87    - Invalid parameter
  1796.              88    - Network data fault
  1797.  
  1798.  
  1799.  
  1800.  
  1801.  
  1802.  
  1803.  
  1804.  
  1805.  
  1806.  
  1807.  
  1808.  
  1809.  
  1810.  
  1811.  
  1812.  
  1813.  
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.                                     - 28 -
  1829.  
  1830.  
  1831.  
  1832.  
  1833.                              ACCI ERROR CODES
  1834.  
  1835.             Code       Meaning
  1836.               0    - No error
  1837.            1000    - Incorrect number of parameters
  1838.            1001    - Too many bytes to read
  1839.            1002    - Date less than 01/01/80 or greater than 12/31/2099
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.  
  1856.  
  1857.  
  1858.  
  1859.  
  1860.  
  1861.  
  1862.  
  1863.  
  1864.  
  1865.  
  1866.  
  1867.  
  1868.  
  1869.  
  1870.  
  1871.  
  1872.  
  1873.  
  1874.  
  1875.  
  1876.  
  1877.  
  1878.  
  1879.  
  1880.  
  1881.  
  1882.  
  1883.  
  1884.  
  1885.  
  1886.  
  1887.                                     - 29 -
  1888.  
  1889.  
  1890.  
  1891.                                 CHAPTER  9
  1892.                            Standalone Utilities
  1893.  
  1894.  
  1895.     FRMSTRUC                             (PRG)
  1896.  
  1897.     A standalone utility PRG that can be compiled and linked with Clipper.
  1898.     This program accepts the FRM file name, opens the file, determines all
  1899.     the breaks, fields, ect. and outputs this information. 
  1900.  
  1901.     Note: This first version only works with .FRM files created with
  1902.           Clipper and dBASE III Plus, not original dBASE.
  1903.  
  1904.     Syntax:      FRMSTRUC <FRM file name>,<option>,<output file>
  1905.  
  1906.     Parameters:  FRM file name - the [drive][path]file name 
  1907.                  Option - P sends output to standard print
  1908.                         - F send output to
  1909.                             Output file - <drive><path>file_name
  1910.                                   the file extension of .TXT is added if 
  1911.                                   there is no extension
  1912.                         - S send output to the screen with pauses
  1913.  
  1914.     Return:      1  if sucessful,  0  if failed
  1915.                  This return code can be tested with the 
  1916.                  DOS Batch command ERRORLEVEL
  1917.  
  1918.                  IF ERRORLEVEL 1   && sucessful
  1919.  
  1920.                  IF ERRORLEVEL 0   && failure
  1921.  
  1922.  
  1923.  
  1924.  
  1925.  
  1926.  
  1927.  
  1928.  
  1929.  
  1930.  
  1931.  
  1932.  
  1933.  
  1934.  
  1935.  
  1936.  
  1937.  
  1938.  
  1939.  
  1940.  
  1941.  
  1942.  
  1943.  
  1944.  
  1945.  
  1946.  
  1947.  
  1948.  
  1949.                                     - 30 -
  1950.